/*
** $Id: lmem.c,v 1.91.1.1 2017/04/19 17:20:42 roberto Exp $
** Interface to Memory Manager
** See Copyright Notice in lua.h
*/

#define lmem_c
#define LUA_CORE

#include "lprefix.h"


#include <stddef.h>

#include "lua.h"

#include "ldebug.h"
#include "ldo.h"
#include "lgc.h"
#include "lmem.h"
#include "lobject.h"
#include "lstate.h"



/*
** About the realloc function:
** void * frealloc (void *ud, void *ptr, size_t osize, size_t nsize);
** ('osize' is the old size, 'nsize' is the new size)
**
** * frealloc(ud, NULL, x, s) creates a new block of size 's' (no
** matter 'x').
**
** * frealloc(ud, p, x, 0) frees the block 'p'
** (in this specific case, frealloc must return NULL);
** particularly, frealloc(ud, NULL, 0, 0) does nothing
** (which is equivalent to free(NULL) in ISO C)
**
** frealloc returns NULL if it cannot create or reallocate the area
** (any reallocation to an equal or smaller size cannot fail!)
*/



#define MINSIZEARRAY  4


/**
 * 动态调整数组或缓冲区的大小。
 *
 * @param L Lua状态机指针。
 * @param block 指向当前内存块的指针。
 * @param size 指向当前大小的指针，函数会更新此值。
 * @param size_elems 每个元素的大小（以字节为单位）。
 * @param limit 允许的最大大小限制。
 * @param what 描述内存块用途的字符串（用于错误消息）。
 * @return 返回调整后的新内存块指针。
 *
 * @note 如果当前大小已经接近或达到限制，函数会尝试将大小设置为限制值。
 *       否则，函数会将大小翻倍（但不会小于最小数组大小 MINSIZEARRAY）。
 *       如果无法进一步扩展，函数会抛出运行时错误。
 */
void *luaM_growaux_(lua_State *L, void *block, int *size, size_t size_elems,
                    int limit, const char *what) {
    void *newblock;
    int newsize;
    if (*size >= limit / 2) {  /* cannot double it? */
        if (*size >= limit)  /* cannot grow even a little? */
            luaG_runerror(L, "too many %s (limit is %d)", what, limit);
        newsize = limit;  /* still have at least one free place */
    } else {
        newsize = (*size) * 2;
        if (newsize < MINSIZEARRAY)
            newsize = MINSIZEARRAY;  /* minimum size */
    }
    newblock = luaM_reallocv(L, block, *size, newsize, size_elems);
    *size = newsize;  /* update only when everything else is OK */
    return newblock;
}


/**
 * 当内存分配失败时（块过大），触发内存分配错误。
 * 此函数用于在内存分配失败时抛出运行时错误，提示块过大。
 *
 * @param L Lua状态机指针。
 * @noreturn 此函数不会返回，而是直接抛出错误。
 */
l_noret luaM_toobig(lua_State *L) {
    luaG_runerror(L, "memory allocation error: block too big");
}


/**
 * 通用的内存重新分配函数。
 *
 * @param L Lua状态机指针。
 * @param block 指向需要重新分配的内存块的指针。如果为NULL，则分配新内存。
 * @param osize 原始内存块的大小（字节数）。如果block为NULL，则忽略此参数。
 * @param nsize 新内存块的大小（字节数）。
 * @return 返回重新分配后的内存块指针。如果分配失败且nsize > 0，则抛出LUA_ERRMEM错误。
 *
 * @note 1. 如果启用了HARDMEMTESTS宏，则在内存增长时可能触发强制垃圾回收。
 *       2. 如果内存分配失败，会尝试通过垃圾回收释放内存后再次分配。
 *       3. 更新全局状态中的GCdebt以反映内存变化。
 */
/*
** generic allocation routine.
*/
void *luaM_realloc_(lua_State *L, void *block, size_t osize, size_t nsize) {
    void *newblock;
    global_State *g = G(L);
    size_t realosize = (block) ? osize : 0;
    lua_assert((realosize == 0) == (block == NULL));
#if defined(HARDMEMTESTS)
    if (nsize > realosize && g->gcrunning)
      luaC_fullgc(L, 1);  /* force a GC whenever possible */
#endif
    newblock = (*g->frealloc)(g->ud, block, osize, nsize);
    if (newblock == NULL && nsize > 0) {
        lua_assert(nsize > realosize);  /* cannot fail when shrinking a block */
        if (g->version) {  /* is state fully built? */
            luaC_fullgc(L, 1);  /* try to free some memory... */
            newblock = (*g->frealloc)(g->ud, block, osize, nsize);  /* try again */
        }
        if (newblock == NULL)
            luaD_throw(L, LUA_ERRMEM);
    }
    lua_assert((nsize == 0) == (newblock == NULL));
    // 更新GCdebt，反映内存使用的变化
    // 原来的负债+新负债-释放的负债
    g->GCdebt = (g->GCdebt + nsize) - realosize;
    return newblock;
}

